/*
 * Copyright 2002-2019 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.config;

import org.springframework.beans.BeansException;
import org.springframework.lang.Nullable;

/**
 * 工厂钩子，允许自定义修改新的Bean实例&mdash。
 * 例如，检查标记接口或用代理来包装Bean。
 *
 * 通常，通过标记接口填充Bean的后处理程序的后处理器将实现{@link #postProcessBeforeInitialization}。
 * 而用代理来包装Bean的后处理程序通常会实现{@link #postProcessAfterInitialization}。
 *
 * 注册
 * 一个{@code ApplicationContext}可以自动检测{@code BeanPostProcessor} beans
 * 并将这些后处理程序应用于随后创建的任何Bean创建的。
 * 一个普通的{@code BeanFactory}允许以编程方式注册后处理程序，并将其应用于通过Bean Factory创建的所有Bean。
 *
 * 排序
 * 在{@code BeanPostProcessor}中被自动检测到的{@code ApplicationContext} Bean
 * 将根据{@link org.springframework.core.PriorityOrdered}和{@link org.springframework.core.Ordered}语义被排序。
 * 相反，用{@code BeanFactory}编程注册的{@code BeanPostProcessor}Bean将按照注册的顺序应用；
 * 通过实现{@code PriorityOrdered}或{@code Ordered}接口表达的任何排序语义将被忽略，用于编程注册的后处理器。
 * 此外，{@link org.springframework.core.annotation.Order @Order}注解对于{@code BeanPostProcessor}Bean来说是不考虑的。
 *
 * @author Juergen Hoeller
 * @author Sam Brannen
 * @since 10.10.2003
 * @see InstantiationAwareBeanPostProcessor
 * @see DestructionAwareBeanPostProcessor
 * @see ConfigurableBeanFactory#addBeanPostProcessor
 * @see BeanFactoryPostProcessor
 */
public interface BeanPostProcessor {

	/**
	 * 在任何Bean初始化回调（如InitializingBean的{@code afterPropertiesSet}）之前，
	 * 将此{@code BeanPostProcessor}应用于给定的新Bean实例或一个自定义的init方法）。) 这个Bean将已经被填充了属性值。
	 * 返回的Bean实例可能是一个围绕原始Bean的包装。默认实现是按原样返回给定的{@code bean}。
	 * @param bean the new bean instance
	 * @param beanName the name of the bean
	 * @return the bean instance to use, either the original or a wrapped one;
	 * if {@code null}, no subsequent BeanPostProcessors will be invoked
	 * @throws org.springframework.beans.BeansException in case of errors
	 * @see org.springframework.beans.factory.InitializingBean#afterPropertiesSet
	 */
	@Nullable
	default Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
		return bean;
	}

	/**
	 * Apply this {@code BeanPostProcessor} to the given new bean instance <i>after</i> any bean
	 * initialization callbacks (like InitializingBean's {@code afterPropertiesSet}
	 * or a custom init-method). The bean will already be populated with property values.
	 * The returned bean instance may be a wrapper around the original.
	 * <p>In case of a FactoryBean, this callback will be invoked for both the FactoryBean
	 * instance and the objects created by the FactoryBean (as of Spring 2.0). The
	 * post-processor can decide whether to apply to either the FactoryBean or created
	 * objects or both through corresponding {@code bean instanceof FactoryBean} checks.
	 * <p>This callback will also be invoked after a short-circuiting triggered by a
	 * {@link InstantiationAwareBeanPostProcessor#postProcessBeforeInstantiation} method,
	 * in contrast to all other {@code BeanPostProcessor} callbacks.
	 * <p>The default implementation returns the given {@code bean} as-is.
	 *
	 * 在任何bean之后将这个{@code BeanPostProcessor}应用到给定的新bean实例
	 * 初始化回调(如InitializingBean的{@code afterPropertiesSet})或者自定义初始化方法)。
	 * bean将已经被属性值填充。
	 * 返回的bean实例可能是原始bean的包装器。
	 * 对于FactoryBean，将为两个FactoryBean调用此回调实例和FactoryBean创建的对象(从Spring 2.0开始)。
	 * 后处理器可以决定是否应用于FactoryBean或已创建的FactoryBean对象或通过相应的{@code bean instanceof FactoryBean}检查。
	 * 触发器触发短路后也会调用此回调函数
	 * {@link InstantiationAwareBeanPostProcessor # postProcessBeforeInstantiation}方法,
	 * 与所有其他{@code BeanPostProcessor}回调相反。
	 * 默认实现按原样返回给定的{@code bean}。
	 *
	 * @param bean the new bean instance
	 * @param beanName the name of the bean
	 * @return the bean instance to use, either the original or a wrapped one;
	 * if {@code null}, no subsequent BeanPostProcessors will be invoked
	 * @throws org.springframework.beans.BeansException in case of errors
	 * @see org.springframework.beans.factory.InitializingBean#afterPropertiesSet
	 * @see org.springframework.beans.factory.FactoryBean
	 */
	@Nullable
	default Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
		return bean;
	}

}
